earthregions

[GI = ] earthregions(name=""; proj="guess", country=false, dataset="", grid=false,
                     res, registration="", exact=false)

Plots or automatically extracts grid/image over a named geographic region.

Many predefined regions are provided via collections. These collections contain names, rectangular geographic boundaries, and access codes for various geographic areas. There are two types of collections: the DCW collection and other collections. The DCW collection is based on the Digital Chart of the World polygons and includes country boundaries (and states for larger countries). This collection allows users to combine regions as needed and plot the country’s boundaries. The other collections are defined by a rectangular boundary and include a name and code for each region. Together, these collections cover a wide range of areas, such as countries, continents, oceans, and more. Users can select a region by its code and then choose to create a map of that region or download topo/bathymetric data (in the form of a grid or image) for that specific area. The collections provide a convenient way to access and work with predefined regions.
Options
This module is a subset of coast but uses also calls to grdcut, plot and the @file server hosted files mechanism.
Examples

Show the contents of the Mainlands collection. We use this as example because it is a small one (contains only the continental parts of some countries that otherwise contain also distant islands) and therefore, good to show what information is displayed to the user.

using GMT
using PrettyTables   # hide
io = IOBuffer() # hide
earthregions("Mainlands")
pato = joinpath(dirname(pathof(GMT))[1:end-4], "share", "named_regions", "") # hide
D = gmtread(pato * "Mainlands_collection.txt")      # hide
PrettyTables.pretty_table(io, ["-85.9506" "-82.5561" "8.0329" "11.2167" "CRC" "Continental Costa Rica" "Mainlands";   # hide
"-81.0788" "-75.1848" "-4.99882" "1.43894" "ECC" "Continental Ecuador" "Mainlands"; # hide
"-9.56" "-6.18" "36.955" "42.16" "PTC" "Continental Portugal" "Mainlands";   # hide
"-9.29092" "4.31502" "35.1852" "43.7915" "ESC" "Continental Spain" "Mainlands"];    # hide
header=["W(lon)","E(lon)","S(lat)","N(lat)","Code","Region","Ref"], backend=Val(:html)) # hide
println("~~~" * String(take!(io)) * "~~~") # hide

Consulting the UN collection we would have found that the “Caribbean” region has the code UN029. So, making a map of the Caribe is as simple as:

using GMT
earthregions("UN029")

But the examples above do not let us plot the country’s borders that help referencing a map. For the time being that is only possible when we use the DCW collection. Next example shows a case with country borders. Also note that for the regions in the DCW (there are 248 of them) we can combine as many countries as we want.

using GMT
earthregions("PT,ES,FR", country=true)

Our last example shows how to extract a topo/bathymetric grid of the “Sea of Azov” and letting the earthregions select the grid resolution. We also show how to make a pretty map with very few commands. Note that for this later case we have much more plotting possibilities than with the earthregions function that is only a tool to select named regions and quickly visualize them.

using GMT
G = earthregions("IHO31", grid=true);
viz(G, shade=true, coast=true, cmap=:earth)

See Also

coast, mosaic